                    Digital Distortion Message Lister
                              Version 1.09
                        Release date: 2009-06-12

                                  by

                             Eric Oulashin
                     Sysop of Digital Distortion BBS
                 BBS internet address: digdist.bbsindex.com
                     Email: eric.oulashin@gmail.com



This file describes the Digital Distortion Message Lister.

Contents
========
1. Introduction
2. Installation & Setup
3. Configuration file
4. DigDistMsgLister class: Properties & methods
5. Revision History

1. Introduction
===============
The Digital Distortion Message Lister is a door application, written in
JavaScript for Synchronet, that lists the messages in the user's current
sub-board.  It was designed to provide an intuitive user interface, allowing
the user to navigate through the list and select a message to read and
optionally reply to.  This script requires Synchronet version 3.13 or higher.

The following is a list of features:
- Displays a formatted summary list of the messages in the user's current sub-board
- Allows the user to read and reply to messages in the sub-board
- Allows the user to navigate forward and backward through the message listings
- Provides a lightbar interface (ANSI required), as well as a traditional user
  interface, which prompts for input after each screenful of message listings
- Supports listing messages in forward or reverse order.  Reverse order has the
  effect of ordering the list descending by date & time, with the newest on top.
  When the script starts, the user will be asked if they want to list the messages
  in reverse order.
- Allows the user to delete and edit existing messages that they've written, if the
  sub-board supports those operations.
- The program settings and colors can be changed via a configuration file.
- The lister is written as a class.  So if desired, message listing can be launched
  in other JavaScript scripts by creating an instance of the DigDistMsgLister class,
  customizing the colors or other properties as desired, and calling the ListMessages
  method.  For the default options, the DigitalDistortionMessageLister.js script
  is suitable.

If a message has been marked for deletion, it will appear with a blinking red
asterisk (*) after the message number in the message list.


2. Installation & Setup
=======================
This package contains three files, including two script files and a configuration
file:
 1. DigitalDistortionMessageLister.js
 2. DigitalDistortionMessageListerReverse.js
 3. DigitalDistortionMessageLister.cfg
The first script, DigitalDistortionMessageLister.js, is the main script.  It
contains the message lister class and default execution code.  This is the script you
will want to run for normal operation.

The files can be placed together in any directory.  No additional initial
configuration is required, aside from placing the script in your command shell or
other scripts where you want to do a message listing.  However, you can edit
the configuration file to suit your tastes.

The second script, DigitalDistortionMessageListerReverse.js, lists messages in
reverse order, regardless of the message order setting in the configuration file.
In your configuration file, if you choose to keep the default behavior of listing
messages in forward order, you may also want to use the second script so that your
users have the option of listing messages in reverse order.
The second script is not a complete copy of the first; therefore, the first script is
required for the second.  The second script can also be used as an example of how to
customize the message lister class, DigDistMsgLister, for different behaviors.

The scripts can be run from a Baja script or a JavaScript application.  For the following
examples, I'll use DigitalDistortionMessageLister.js.  The following instructions assume
that the scripts and configuration file are placed in the SBBS "exec" directory.

To use the message lister in a Baja script, include the following line to run the
message lister:
   exec "?DigitalDistortionMessageLister.js"

Running the script from JavaScript can be done in several ways:
1) The load() function, as in the following:
   load("DigitalDistortionMessageLister.js");
2) The message lister code is actually contained in a JavaScript class, called DigDistMsgLister.
   If you want to change the colors, user interface used, or other options, you can follow
   these steps:
   1. Create your own JavaScript source file
   2. At the top of your JavaScript source file, include DigitalDistortionMessageLister.js
      using the load() function, and pass false as the second parameter, as in the following
      example:
        load("DigitalDistortionMessageLister.js", false);
      The false will cause the lister not to execute; the script will simply provide the class
      definition for your use. (Note: Using load() this way is a way to pass arguments to a
      JavaScript source file, in the argv array.  In DigitalDistortionMessageLister.js, the
      false is recognized as argv[0].)
   3. Create a DigDistMsgLister instance, set any options you'd like to set, and call
      ListMessages(), passing the sub-board code to list.  Example:
        var msgLister = new DigDistMsgLister();
        msgLister.interfaceStyle = "Lightbar";
        msgLister.ListMessages(user.cursub);
      Note: To change to the traditional user interface (scrolling, prompt the user at the
      end of each page), you can change the interfaceStyle property to "Traditional",
      as follows:
        msgLister.interfaceStyle = "Traditional";
      One of the other properties, displayBoardInfoInHeader, can be changed to toggle
      the display of the message sub-board information in the header above the message
      listing.  It takes a boolean.  Example:
        msgLister.displayBoardInfoInHeader = true;
      Another property, reverseOrder, specifies whether or not to display the messages
      in reverse order (descending by date & time).  It can be either a boolean (true
      or false), or the string "ask" to ask the user whether they want the list
      displayed in reverse.


3. Configuration file
=====================
If you want to change the default beavior and colors, you can edit the configuration
file, which is a plain text file.  The configuration file has two sections: A behavior
section (denoted by [BEHAVIOR]) and a colors section (denoted by [COLORS]).  For each
setting or color, the syntax is as folows:

setting=value

where "setting" is the behavior setting or color, and "value" is the corresponding
value for the setting/color.  The colors are Synchronet color codes.

Also, comments are allowed in the configuration file.  Comments begin with a
semicolon (;).

Behavior section
----------------
Setting                               Description
-------                               -----------
interfaceStyle                        String: The user interface to use.  Valid values
                                      are "Traditional" (traditional user interface
                                      with user prompted for input at the end of each
                                      screenful) and "Lightbar" (use the lightbar user
                                      interface).

displayBoardInfoInHeader              true/false: Whether or not to display sub-board
                                      information above the column headers when listing
                                      the message information.  If this is set to true,
                                      2 extra lines on the screen will be used at the top
                                      to display message group and sub-board.

reverseOrder                          true/false: Whether or not to display the list
                                      in reverse order, or the string "ask" to ask the user
                                      whether they want the list displayed in reverse.  If
                                      the list is displayed in reverse, that has the effect
                                      of listing in descending order by  date & time.

promptToContinueListingMessages       true/false: Whether or not to prompt the user to continue
                                      listing messages after a message is read.

Colors section
--------------
Color setting                        Description
-------------                        -----------
headerMsgGroupText                   Header line displaying the message group, for the
                                     text Current msg group: 
headerMsgGroupName                   Header line displaying the message group, for the
                                     message group

headerSubBoardText                   Header line displaying the message sub-board, for the
                                     text Current msg sub-board: 
headerMsgSubBoardName                Header line displaying the message sub-board, for the
                                     message sub-board

listColHeader                        Column names for the list

headerSeparatorLine                  The line separating the column names from the list

msgNum                               Message number (in the list)
from                                 Sender name (in the list)
to                                   Destination name (in the list)
subject                              Message subject (in the list)
date                                 Message date (in the list)
time                                 Message time (in the list)

msgHighlightBkg                      Message highlighting background color (for lightbar mode)

contPromptMain                       For the traditional user interface: The text
                                     displayed in the per-screen user prompt

contPromptHotkeys                    For the traditional user interface: The hotkeys
                                     displayed in the per-screen user prompt

contPromptUserInput                  For the traditional user interface: User input
                                     at screen pauses

msgBody                              The message body, when the user chooses to
                                     read a message

readMsgConfirm                       Text used for asking the user if they really want to
                                     read the message
readMsgConfirmNumber                 For the message number displayed when asking the user
                                     if they really want to read the message

afterReadMsg_ListMorePrompt          Text used for asking the user if they want to continue
                                     listing messages
	
helpScreen                           For the text used in the help screen


4. DigDistMsgLister class: Properties & methods
===============================================
The following are the properties and methods of the DigDistMsgLister class, which
can be used in JavaScript scripts:
Property name                         Description
-------------                         -----------
subBoardCode                          String: This is the Synchronet sub-board code; it
                                      specifies which message area to use.  This can
                                      also be "mail" for personal email.

interfaceStyle                        String: The user interface to use.  Valid values
                                      are "Traditional" (traditional user interface
                                      with user prompted for input at the end of each
                                      screenful) and "Lightbar" (use the lightbar user
                                      interface).

reverseOrder                          Boolean: Whether or not to display the list in
                                      reverse order, or the string "ask" to ask the user
                                      whether they want the list displayed in reverse.  If
                                      the list is displayed in reverse, that has the effect
                                      of listing in descending order by  date & time.

displayBoardInfoInHeader              Boolean: Whether or not to display sub-board
                                      information above the column headers when listing
                                      the message information.  If this is set to true,
                                      2 extra lines on the screen will be used at the top
                                      to display message group and sub-board.

promptToContinueListingMessages       Boolean: Whether or not to prompt the user to continue
                                      listing messages after a message is read.

sMsgInfoFormatStr                     The format string (printf-style) used for displaying
                                      message information lines in the message listing.

sMsgInfoFormatHighlightStr            Same as sMsgInfoFormatStr, but used for highlighting
                                      the line on screen.  The only difference is the colors.

sStartContinuePrompt                  For the traditional user interface: The text used
                                      for prompting the user at the end of the first page.

sContinuePrompt                       For the traditional user interface: The text used
                                      for prompting the user at the end of the page (except
                                      for the first & last pages).

sEndContinuePrompt                    For the traditional user interface: The text used
                                      for prompting the user at the end of the last page.

sOnlyOnePageContinuePrompt            For the traditional user interface: The text used
                                      for prompting the user at the end of the page, when
                                      there is only one page.

sLightbarModeHelpLine                 For the lightbar user interface: The help text that
                                      appears on the bottom of the screen.

colors                                An array, indexed with strings, containing the colors
                                      used for the different parts of the lister.  The
                                      array index is a description of what the color is
                                      used for.  These descriptions are the same as the
                                      color setting names used in the configuration file
                                      (see section 3: Configuration file).
                                      
Methods
-------
Method name                           Description
-----------                           -----------
DigDistMsgLister(pSubBoardCode)       This is the constructor for DigDistMsgLister
                                      objects.  pSubBoardCode is optional and specifies
                                      the Synchronet sub-board code, or "mail" for
                                      personal email.  If the sub-board code is not
                                      provided here, it must be specified by setting
                                      the subBoardCode property or provided for
                                      ListMessages().
                                      

ListMessages(pSubBoardCode)           Performs the message listing, given a sub-board
                                      code.  pSubBoardCode is optional and specifies
                                      the Synchronet sub-board code, or "mail" for
                                      personal email.  If the sub-board code is not
                                      provided here, it must be specified by setting
                                      the subBoardCode property or provided when
                                      the constructor is called.
                                      This method uses the interface style specified
                                      by the interfaceStyle property.  Note that
                                      the lightbar interface requires an ANSI terminal,
                                      and if the interfaceStyle property is set to
                                      "Lightbar" and the user's terminal doesn't
                                      support ANSI, the lister will fall back to
                                      the traditional user interface style.


5. Revision History
===================
Version  Date         Description
-------  ----         -----------
1.09     2009-06-12   Added the ability to allow the user to delete and edit existing messages
                      if those options are enabled for the sub-board.  Updated the reply
                      functionality to honor the sub-board's setting for whether or not to
                      allow message quoting.  Added the ability to read program settings from
                      a configuration file.
1.08     2009-06-07   Disabled the yes/no prompt asking the user if they want to continue
                      listing messages.  Added a property, promptToContinueListingMessages,
                      to control whether or not the user will be asked to continue listing
                      messages after a message is selected for reading.  Also, I disabled
                      the prompt for whether or not to display the messages in reverse order
                      when the script starts up and made it default to listing the messages
                      in forward order.  For this release, I've started including my script
                      my script DigitalDistortionMessageListerReverse.js, which lists messages
                      in reverse order.
1.07     2009-05-28   Fixed a bug in the lightbar interface: When listing in reverse, if
                      the last page of messages fit perfectly on the screen, pressing L
                      to go to the last page did not correctly set the top message.
1.06     2009-05-26   Added the ability to (optionally) display the list descending by
                      date & time (reverse order).  The reverseOrder property of the
                      DigDistMsgLister class can be set to enable this feature (it
                      defaults to false).  Added an optional parameter to the constructor
                      to set the sub-board code.
                      Fixed a bug: When displaying the message group & sub-board
                      information above the list, this script now uses the information
                      from the local MsgBase object rather than the global bbs object,
                      since the script could be displaying a different group than
                      what's set in the global bbs object.
                      Fixed a bug that prevented the user from replying when listing
                      personal email.
1.05     2009-05-23   Fixed a bug in the lightbar user interface: If the last page of
                      messages fit perfectly on the screen, then pressing L to go to the
                      last page would go past the last message.  Now it will go to the
                      proper screenful of messages.
1.04     2009-05-18   Fixed a bug that affecting replying to messages: It was trying to
                      post the reply message incorrectly and to the wrong sub-board,
                      causing an error.
                      Fixed a bug in the lightbar interface: If the END key was pressed
                      on a page that was only partially full of messages, it would go
                      to the last line on the screen rather than the last message (it
                      assumed that each page was full).
1.03     2009-05-16   Improved input speed for the lightbar user interface.
                      Added support for the ESC key to quit the listing.
                      Bug fix: For the lightbar user interface, when the user
                      starts typing a message number, if the user cancels
                      the message number input, it would continue with an
                      invalid message number.  Now it will just go back to
                      the message listing.
1.02     2009-05-13   Updated to be a stand-alone script (no other .js dependencies).
1.01     2009-05-11   Fixed a typo in a variable name for the lightbar interface which caused the
                      script to exit when the user pressed F to go back to the first page.
1.00     2009-05-10   First public release